IRIX Base Documentation 2001 May/SGI IRIX Base Documentation 2001 May.iso/usr/share/catman/p_man/cat3/librw/RWTIsvSlist.z/RWTIsvSlist

Text File | 1998-10-30 | 15.7 KB | 463 lines

RRRRWWWWTTTTIIIIssssvvvvSSSSlllliiiisssstttt((((3333CCCC++++++++))))                                            RRRRWWWWTTTTIIIIssssvvvvSSSSlllliiiisssstttt((((3333CCCC++++++++))))



NNNNaaaammmmeeee
     RWTIsvSlist<T> - Rogue Wave library class

SSSSyyyynnnnooooppppssssiiiissss
              #include <rw/tislist.h>



              RWTIsvSlist<T> list;




DDDDeeeessssccccrrrriiiippppttttoooonnnn
     Class RRRRWWWWTTTTIIIIssssvvvvSSSSlllliiiisssstttt<<<<TTTT>>>> is a class that implements intrusive singly-linked
     lists. An intrusive list is one where the member of the list must inherit
     from a common base class, in this case RRRRWWWWIIIIssssvvvvSSSSlllliiiinnnnkkkk.  The advantage of such
     a list is that memory and space requirements are kept to a minimum.  The
     disadvantage is that the inheritance hierarchy is inflexible, making it
     slightly more difficult to use with an existing class.  Class
     RRRRWWWWTTTTVVVVaaaallllSSSSlllliiiisssstttt<<<<TTTT>>>> is offered as an alternative, non-intrusive, linked list.
     See Stroustrup (1991; Section 8.3.1) for more information about intrusive
     lists.  NNNNooootttteeee tttthhhhaaaatttt wwwwhhhheeeennnn yyyyoooouuuu iiiinnnnsssseeeerrrrtttt aaaannnn iiiitttteeeemmmm iiiinnnnttttoooo aaaannnn iiiinnnnttttrrrruuuussssiiiivvvveeee lllliiiisssstttt,,,, tttthhhheeee
     aaaaccccttttuuuuaaaallll iiiitttteeeemmmm ((((nnnnooootttt aaaa ccccooooppppyyyy)))) iiiissss iiiinnnnsssseeeerrrrtttteeeedddd....  BBBBeeeeccccaaaauuuusssseeee eeeeaaaacccchhhh iiiitttteeeemmmm ccccaaaarrrrrrrriiiieeeessss oooonnnnllllyyyy oooonnnneeee
     lllliiiinnnnkkkk ffffiiiieeeelllldddd,,,, tttthhhheeee ssssaaaammmmeeee iiiitttteeeemmmm ccccaaaannnnnnnnooootttt bbbbeeee iiiinnnnsssseeeerrrrtttteeeedddd iiiinnnnttttoooo mmmmoooorrrreeee tttthhhhaaaannnn oooonnnneeee lllliiiisssstttt,,,, nnnnoooorrrr
     ccccaaaannnn iiiitttt bbbbeeee iiiinnnnsssseeeerrrrtttteeeedddd iiiinnnnttttoooo tttthhhheeee ssssaaaammmmeeee lllliiiisssstttt mmmmoooorrrreeee tttthhhhaaaannnn oooonnnncccceeee....


EEEExxxxaaaammmmpppplllleeee
              #include <rw/tislist.h>
          #include <rw/rstream.h>
          #include <string.h>


              struct Symbol : public RWIsvSlink



              { char name[10];
            Symbol( const char* cs)
             { strncpy(name, cs, sizeof(name)); name[9] = ' '; }
          };


              void printem(Symbol* s, void*) { cout << s->name << endl; }
          main(){



                RWTIsvSlist<Symbol> list;
            list.insert( new Symbol("one") );
            list.insert( new Symbol("two") );



                                                                        PPPPaaaaggggeeee 1111






RRRRWWWWTTTTIIIIssssvvvvSSSSlllliiiisssstttt((((3333CCCC++++++++))))                                            RRRRWWWWTTTTIIIIssssvvvvSSSSlllliiiisssstttt((((3333CCCC++++++++))))



            list.prepend( new Symbol("zero") );


                list.apply(printem, 0);



                list.clearAndDestroy();  // Deletes the items inserted into
                                     // the list
            return 0;
          }

     PPPPrrrrooooggggrrrraaaammmm OOOOuuuuttttppppuuuutttt::::

              zero
          one

PPPPuuuubbbblllliiiicccc CCCCoooonnnnssssttttrrrruuuuccccttttoooorrrrssss
     two



              RRRRWWWWTTTTIIIIssssvvvvSSSSlllliiiisssstttt();


     Constructs an empty list.

              RRRRWWWWTTTTIIIIssssvvvvSSSSlllliiiisssstttt(T* a);


     Constructs a list with the single item pointed to by aaaa in it.

PPPPuuuubbbblllliiiicccc MMMMeeeemmmmbbbbeeeerrrr FFFFuuuunnnnccccttttiiiioooonnnnssss
              void
          aaaappppppppeeeennnndddd(T* a);


     Appends the item pointed to by aaaa to the end of the list.

              void
          aaaappppppppllllyyyy(void (*applyFun)(T*, void*), void* d);


     Calls the function pointed to by aaaappppppppllllyyyyFFFFuuuunnnn to every item in the
     collection.  This must have the prototype:

              void yyyyoooouuuurrrrFFFFuuuunnnn(T* item, void* d);








                                                                        PPPPaaaaggggeeee 2222






RRRRWWWWTTTTIIIIssssvvvvSSSSlllliiiisssstttt((((3333CCCC++++++++))))                                            RRRRWWWWTTTTIIIIssssvvvvSSSSlllliiiisssstttt((((3333CCCC++++++++))))





     The item will be passed in as argument iiiitttteeeemmmm.  Client data may be passed
     through as parameter dddd.

              T*
          aaaatttt(size_t i) const;


     Returns the item at index iiii.  The index iiii must be between zero and the
     number of items in the collection less one, or an exception of type
     TTTTOOOOOOOOLLLL____IIIINNNNDDDDEEEEXXXX will be thrown.

              void
          cccclllleeeeaaaarrrr();


     Removes all items from the list.

              void
          cccclllleeeeaaaarrrrAAAAnnnnddddDDDDeeeessssttttrrrrooooyyyy();


     Removes aaaannnndddd ccccaaaallllllllssss ddddeeeelllleeeetttteeee for each item in the list.  Note that this
     assumes that each item was allocated off the heap.

              RWBoolean
          ccccoooonnnnttttaaaaiiiinnnnssss(RWBoolean (*testFun)(const T*, void*), void* d)
                   const;


     Returns TTTTRRRRUUUUEEEE if the list contains an item for which the user-defined
     "tester" function pointed to by tttteeeessssttttFFFFuuuunnnn returns TTTTRRRRUUUUEEEE .  The tester
     function must have the prototype:

              RWBoolean yyyyoooouuuurrrrTTTTeeeesssstttteeeerrrr(const T* item, void* d);





     For each item in the list this function will be called with the item as
     the first argument.  Client data may be passed through as parameter dddd.

              RWBoolean
          ccccoooonnnnttttaaaaiiiinnnnssssRRRReeeeffffeeeerrrreeeennnncccceeee(const T* a) const;


     Returns TTTTRRRRUUUUEEEE if the list contains an item with the address aaaa.






                                                                        PPPPaaaaggggeeee 3333






RRRRWWWWTTTTIIIIssssvvvvSSSSlllliiiisssstttt((((3333CCCC++++++++))))                                            RRRRWWWWTTTTIIIIssssvvvvSSSSlllliiiisssstttt((((3333CCCC++++++++))))



              size_t
          eeeennnnttttrrrriiiieeeessss() const;


     Returns the number of items currently in the list.

              T*
          ffffiiiinnnndddd(RWBoolean (*testFun)(const T*, void*),void* d) const;


     Returns the first item in the list for which the user-defined "tester"
     function pointed to by tttteeeessssttttFFFFuuuunnnn returns TTTTRRRRUUUUEEEE.  If there is no such item,
     then returns nnnniiiillll.  The tester function must have the prototype:

              RWBoolean yyyyoooouuuurrrrTTTTeeeesssstttteeeerrrr(const T* item, void* d);





     For each item in the list this function will be called with the item as
     the first argument.  Client data may be passed through as parameter dddd.

              T*
          ffffiiiirrrrsssstttt() const;


     Returns (but does not remove) the first item in the list, or nnnniiiillll if the
     list is empty.

              T*
          ggggeeeetttt();


     Returns aaaannnndddd rrrreeeemmmmoooovvvveeeessss the first item in the list, or nnnniiiillll if the list is
     empty.

              size_t
          iiiinnnnddddeeeexxxx(RWBoolean (*testFun)(const T*, void*),void* d) const;


     Returns the index of the first item in the list for which the user-
     defined "tester" function pointed to by tttteeeessssttttFFFFuuuunnnn returns TTTTRRRRUUUUEEEE.  If there
     is no such item, then returns RRRRWWWW____NNNNPPPPOOOOSSSS.  The tester function must have the
     prototype:

              RWBoolean yyyyoooouuuurrrrTTTTeeeesssstttteeeerrrr(const T* item, void* d);








                                                                        PPPPaaaaggggeeee 4444






RRRRWWWWTTTTIIIIssssvvvvSSSSlllliiiisssstttt((((3333CCCC++++++++))))                                            RRRRWWWWTTTTIIIIssssvvvvSSSSlllliiiisssstttt((((3333CCCC++++++++))))





     For each item in the list this function will be called with the item as
     the first argument.  Client data may be passed through as parameter dddd.

              void
          iiiinnnnsssseeeerrrrtttt(T* a);


     Appends the item pointed to by aaaa to the end of the list.  This item
     cannot be inserted into more than one list, nor can it be inserted into
     the same list more than once.

              void
          iiiinnnnsssseeeerrrrttttAAAAtttt(size_t i, T* a);


     Insert the item pointed to by aaaa at the index position iiii.  This position
     must be between zero and the number of items in the list, or an exception
     of type TTTTOOOOOOOOLLLL____IIIINNNNDDDDEEEEXXXX will be thrown.  The item cannot be inserted into more
     than one list, nor can it be inserted into the same list more than once.

              RWBoolean
          iiiissssEEEEmmmmppppttttyyyy() const;


     Returns TTTTRRRRUUUUEEEE if there are no items in the list, FFFFAAAALLLLSSSSEEEE otherwise.

              T*
          llllaaaasssstttt() const;


     Returns (but does not remove) the last item in the list, or nnnniiiillll if the
     list is empty.

              size_t
          ooooccccccccuuuurrrrrrrreeeennnncccceeeessssOOOOffff(RWBoolean (*testFun)(const T*, void*),void* d)
                        const;


     Traverses the list and returns the number of times for which the user-
     defined "tester" function pointed to by tttteeeessssttttFFFFuuuunnnn returned TTTTRRRRUUUUEEEE .  The
     tester function must have the prototype:

              RWBoolean yyyyoooouuuurrrrTTTTeeeesssstttteeeerrrr(const T* item, void* d);





     For each item in the list this function will be called with the item as
     the first argument.  Client data may be passed through as parameter dddd.



                                                                        PPPPaaaaggggeeee 5555






RRRRWWWWTTTTIIIIssssvvvvSSSSlllliiiisssstttt((((3333CCCC++++++++))))                                            RRRRWWWWTTTTIIIIssssvvvvSSSSlllliiiisssstttt((((3333CCCC++++++++))))



              size_t
          ooooccccccccuuuurrrrrrrreeeennnncccceeeessssOOOOffffRRRReeeeffffeeeerrrreeeennnncccceeee(const T* a) const;


     Returns the number of times which the item pointed to by aaaa occurs in the
     list.  Because items cannot be inserted into a list more than once, this
     function can only return zero or one.

              void
          pppprrrreeeeppppeeeennnndddd(T* a);


     Prepends the item pointed to by aaaa to the beginning of the list.

              T*
          rrrreeeemmmmoooovvvveeee(RWBoolean (*testFun)(const T*, void*),void* d);


     Removes and returns the first item for which the user-defined tester
     function pointed to by tttteeeessssttttFFFFuuuunnnn returns TTTTRRRRUUUUEEEE, or nnnniiiillll if there is no such
     item.  The tester function must have the prototype:

              RWBoolean yyyyoooouuuurrrrTTTTeeeesssstttteeeerrrr(const T* item, void* d);





     For each item in the list this function will be called with the item as
     the first argument.  Client data may be passed through as parameter dddd.

              T*
          rrrreeeemmmmoooovvvveeeeAAAAtttt(size_t i);


     Removes and returns the item at index iiii.  The index iiii must be between
     zero and the number of items in the collection less one or an exception
     of type TTTTOOOOOOOOLLLL____IIIINNNNDDDDEEEEXXXX will be thrown.

              T*
          rrrreeeemmmmoooovvvveeeeFFFFiiiirrrrsssstttt();


     Removes and returns the first item in the list, or nnnniiiillll if there are no
     items in the list.

              T*
          rrrreeeemmmmoooovvvveeeeLLLLaaaasssstttt();


     Removes and returns the last item in the list, or nnnniiiillll if there are no
     items in the list.  This function is relatively slow because removing the



                                                                        PPPPaaaaggggeeee 6666






RRRRWWWWTTTTIIIIssssvvvvSSSSlllliiiisssstttt((((3333CCCC++++++++))))                                            RRRRWWWWTTTTIIIIssssvvvvSSSSlllliiiisssstttt((((3333CCCC++++++++))))



     last link in a singly-linked list necessitates access to the next-to-
     the-last link, requiring the whole list to be searched.

              T*
          rrrreeeemmmmoooovvvveeeeRRRReeeeffffeeeerrrreeeennnncccceeee(T* a);


     Removes and returns the link with address aaaa.  The link must be in the
     list.  In a singly-linked list this function is not very efficient.














































                                                                        PPPPaaaaggggeeee 7777